 
  

 






<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 
<html>

<!-- Mirrored from www.javapractices.com/topic/TopicAction.do;jsessionid=4FCCB481C702D708A7360133D128E359?Id=48 by HTTrack Website Copier/3.x [XR&CO'2010], Sun, 12 Jun 2011 17:28:07 GMT -->
<!-- Added by HTTrack --><meta http-equiv="content-type" content="text/html;charset=UTF-8"><!-- /Added by HTTrack -->
<head>
 <title>
  Java Practices -> Document thread safety
 </title>
 <link rel="stylesheet" type="text/css" href="../stylesheet8.css" media="all">
 
 <link rel="shortcut icon" href='../images/favicon.ico' type="image/vnd.microsoft.icon">
 <meta name="description" content="Concise presentations of java programming practices, tasks, and conventions, amply illustrated with syntax highlighted code examples.">
 
 <meta name='keywords' content='API,immutable,javadoc,mutability,mutable,spec,specification,synchronized,thread,java,java programming,java practices,java idiom,java style,java design patterns,java coding conventions,'>
 
 
</head>
 
<body>


<div class='menu-bar'>
 
  <a href='../home/HomeAction.html' title='Table of Contents'>Home</a> |
  <a href='../vote/VoteSummaryAction-2.html' title='View Poll Results'>Poll</a> |
   
  <A href='../feedback/FeedbackAction451f-2.html?Operation=Show' title='Send Your Feedback'>Wiki</a> |
  <b><a href='../source/SourceAction-2.html' title='Grab Source Code'>Source Code</a></b><IMG class='no-margin' SRC="../images/goldstar.gif" ALT=""> |

  <a href='http://www.web4j.com/Java_Web_Application_Framework_Overview.jsp?From=1' title='Free Download - Java Web Application Framework'><b>WEB4J</b></a> |
  
  <a href='http://www.date4j.net/' title='Replacement for java.util.Date'><b>DATE4J</b></a> |

   <a href='../references/ReferencesAction-2.html' title='References'>Links</a>
   
  <form action='http://www.javapractices.com/search/SearchAction.do' method='get' class='search-form'>
   <input type='text' name='SearchTerms' value="" size=12 maxlength=50 class='search'>
   <input type='submit' value="Search">
  </form>
 
</div>

<P>



  

 






<p class="display-messages">

 

 

</p>


<div class="main-layout">
 
   

 




<div class='page-title'>Document thread safety</div>

<div class='main-body'>
 
<br>Javadoc comments should describe how the responsibilities for ensuring
correct multi-threaded behaviour are shared between a class and its caller.
This is equivalent to stating the circumstances, if any, in which the caller
must explicitly obtain some lock before performing certain operations.
The central question to be answered by the documentation is :
<p>"<i>When do these objects require external synchronization?</i>"
<p>Here, "operations" on an object come in two flavours :
<ul>
<li>
single-call operations, where only a single method is called</li>

<li>
multiple-call operations, where more than one method is called, and they
are treated as a single unit ; the classic example is iteration over a
collection</li>
</ul>
(The naming convention described below is after the style of <i><a href="http://www.amazon.com/exec/obidos/ASIN/0201310058/ref=nosim/javapractices-20">Effective
Java</a></i>, by Joshua Bloch.)
<p>Documentation of thread safety is simplest when the responsibility for
ensuring correct multi-threaded behaviour rests entirely with one party,
and is not shared between the class and its caller :
<p><b>immutable</b> - the caller <i>never</i> needs to obtain a lock explicitly
before performing any operation, either single-call or multiple-call. Since
<a href="TopicActiond838-2.html">immutable objects</a> never change state after construction, ensuring data
integrity during multi-threaded use is not an issue. Here, all responsibility
for correct multi-threaded behaviour rests with the class itself.
<p><b>thread-compatible</b>&nbsp; - the caller <i>always</i> needs to obtain
a lock explicitly before performing any operation, either single-call or
multiple-call. An example would be a class whose internals do not perform
any synchronization whatsoever, such as <tt><a href="http://java.sun.com/javase/6/docs/api/java/util/ArrayList.html">ArrayList</a></tt>.
Here, all responsibility for correct multi-threaded behaviour rests with
the caller.
<p><b>thread-hostile</b> - operations cannot be performed safely in a multi-threaded
environment, even when a lock is always obtained explicitly. This is a
rare pathological case.
<p>Documentation of thread-safety is more challenging in the following cases, where
responsibility for correct behaviour is <em>shared</em> between a class and its
caller :
<p><b>thread-safe</b> - the caller <i>never</i> needs to obtain a lock
explicitly for single-call operations, but <i>does</i> need to obtain a
lock during multiple-call operations. An example is a mutable class whose
implementation performs all necessary synchronization for each individual
method, but is being used in a multiple-call operation. Here, the responsibility
for correct multi-threaded behaviour is shared between the class and its
caller.
<p><b>conditionally thread-safe</b> - same as thread-safe, with the added
distinction that there is <i>at least one method</i> whose sole use is
as part of a multiple-call operation.&nbsp; The caller must always obtain
a lock explicitly before using such a method. Again, the responsibility
for correct multi-threaded behaviour is shared between the class and its
caller.
<p>(Note that <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html">javadoc
1.4</a> includes the <tt>-tag</tt> option, whereby simple custom tags may
be defined. One might define a <tt>@needs.External.Synch</tt> tag, for
example, to document thread safety issues.)

<P><span class='highlight'>In typical business applications, most classes will likely be either 
<b>immutable</b> or <b>thread-compatible</b>.</span>
<br>
<br>

</div>




<div class='topic-section'>See Also :</div>
<div class='main-body'>
 
  
  <a href='TopicActiond838-2.html?Id=29'>Immutable objects</a> <br>
 
  
  <a href='TopicActionebc1-2.html?Id=60'>Use javadoc liberally</a> <br>
 
  
  <a href='TopicActiona6f3-2.html?Id=67'>Synchronized is implementation detail</a> <br>
 
</div>


<div class='topic-section'>Would you use this technique?</div>
<div class='main-body'>
  
  <form action="http://www.javapractices.com/vote/AddVoteAction.do" method='post'>
    Yes<input type='radio' name='Choice' value='Y' >
    &nbsp;&nbsp;No<input type='radio' name='Choice' value='N'>
    &nbsp;&nbsp;Undecided<input type='radio' name='Choice' value="?" >
    &nbsp;&nbsp;<input type=submit value="Vote" >
    <input type='hidden' name='Operation' value='Apply'>
    <input type='hidden' name='TopicId' value='48'>
  </form>
</div>

<div style='height:10.0em;'></div>

 
 
</div>

  

 





<div align='center' class='legalese'>  
&copy; 2011 Hirondelle Systems |
<a href='../source/SourceAction-2.html'><b>Source Code</b></a><IMG class='no-margin' SRC="../images/goldstar.gif" ALT=""> |
<a href="mailto:webmaster@javapractices.com">Contact</a> |
<a href="http://creativecommons.org/licenses/by-nc-sa/1.0/">License</a> |
<a href='../apps/cjp.rss'>RSS</a>
<!-- ukey="2AC36CD2" -->
<!-- ckey="16DF3D87" -->
<br>

 Individual code snippets can be used under this <a href='../LICENSE.txt'>BSD license</a> - Last updated on June 6, 2010.<br>
 Over 150,000 unique IPs last month - <span title='Java Practices 2.6.5, Mon May 16 00:00:00 EDT 2011'>Built with</span> <a href='http://www.web4j.com/'>WEB4J</a>.<br>
 - In Memoriam : Bill Dirani -
</div>

<script src="../../www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-2633428-1";
urchinTracker();
</script>



</body>

<!-- Mirrored from www.javapractices.com/topic/TopicAction.do;jsessionid=4FCCB481C702D708A7360133D128E359?Id=48 by HTTrack Website Copier/3.x [XR&CO'2010], Sun, 12 Jun 2011 17:28:07 GMT -->
<!-- Added by HTTrack --><meta http-equiv="content-type" content="text/html;charset=UTF-8"><!-- /Added by HTTrack -->
</html>
